<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>rrdgraph_data</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>

<body>



<h1 id="NAME">NAME</h1>

<p>rrdgraph_data - preparing data for graphing in rrdtool graph</p>

<h1 id="SYNOPSIS">SYNOPSIS</h1>

<p><b>DEF:</b><i>&lt;vname&gt;</i>=<i>&lt;rrdfile&gt;</i>:<i>&lt;ds-name&gt;</i>:<i>&lt;CF&gt;</i>[:step=<i>&lt;step&gt;</i>][:start=<i>&lt;time&gt;</i>][:end=<i>&lt;time&gt;</i>][:reduce=<i>&lt;<b>CF</b>&gt;</i>][:daemon=<i>&lt;address&gt;</i>]</p>

<p><b>VDEF</b>:<i>vname</i>=<i>RPN expression</i></p>

<p><b>CDEF</b>:<i>vname</i>=<i>RPN expression</i></p>

<h1 id="DESCRIPTION">DESCRIPTION</h1>

<p>These three instructions extract data values out of the <b>RRD</b> files, optionally altering them (think, for example, of a bytes to bits conversion). If so desired, you can also define variables containing useful information such as maximum, minimum etcetera. Two of the instructions use a language called <b>RPN</b> which is described in its own manual page.</p>

<p>Variable names (<i>vname</i>) must be made up strings of the following characters <code>A-Z, a-z, 0-9, _, -</code> and a maximum length of 255 characters.</p>

<p>When picking variable names, make sure you do not choose a name that is already taken by an RPN operator. A safe bet is to use lowercase or mixed case names for variables since operators will always be in uppercase.</p>

<h1 id="DEF">DEF</h1>

<p><b>DEF:</b><i>&lt;vname&gt;</i>=<i>&lt;rrdfile&gt;</i>:<i>&lt;ds-name&gt;</i>:<i>&lt;CF&gt;</i>[:step=<i>&lt;step&gt;</i>][:start=<i>&lt;time&gt;</i>][:end=<i>&lt;time&gt;</i>][:reduce=<i>&lt;<b>CF</b>&gt;</i>][:daemon=<i>&lt;address&gt;</i>]</p>

<p>This command fetches data from an <b>RRD</b> file. The virtual name <i>vname</i> can then be used throughout the rest of the script. By default, an <b>RRA</b> which contains the correct consolidated data at an appropriate resolution will be chosen. The resolution can be overridden with the <a href="./rrdgraph.html#item_Time">--step</a> option. The resolution can again be overridden by specifying the <b>step size</b>. The time span of this data is the same as for the graph by default, you can override this by specifying <b>start and end</b>. Remember to escape colons in the time specification!</p>

<p>If the resolution of the data is higher than the resolution of the graph, the data will be further consolidated. This may result in a graph that spans slightly more time than requested. Ideally each point in the graph should correspond with one <b>CDP</b> from an <b>RRA</b>. For instance, if your <b>RRD</b> has an <b>RRA</b> with a resolution of 1800 seconds per <b>CDP</b>, you should create an image with width 400 and time span 400*1800 seconds (use appropriate start and end times, such as <code>--start end-8days8hours</code>).</p>

<p>If consolidation needs to be done, the <b>CF</b> of the <b>RRA</b> specified in the <b>DEF</b> itself will be used to reduce the data density. This behavior can be changed using <code>:reduce=<i>&lt;<b>CF</b>&gt;</i></code>. This optional parameter specifies the <b>CF</b> to use during the data reduction phase.</p>

<p>It is possible to request single data sources from a specific <i>RRDCacheD</i>, see <a href="./rrdcached.html">rrdcached</a>, using the <code>:daemon=<i>&lt;address&gt;</i></code> parameter. The value given to this parameter follows the same syntax as other means to specify the address of the caching daemon. It is described in detail in <a href="./rrdcached.html">rrdcached</a>. Beware, however, that colons (in IPv6 addresses and as a port separator, for example) need to be escaped using a backslash.</p>

<p>Example:</p>

<pre><code>        DEF:ds0=router.rrd:ds0:AVERAGE
        DEF:ds0weekly=router.rrd:ds0:AVERAGE:step=7200
        DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=end-1h
        DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=11\:00:end=start+1h
        DEF:ds0weekly=router.rrd:ds0:AVERAGE:daemon=collect1.example.com</code></pre>

<h1 id="VDEF">VDEF</h1>

<p><b>VDEF</b>:<i>vname</i>=<i>RPN expression</i></p>

<p>This command returns a value and/or a time according to the <b>RPN</b> statements used. The resulting <i>vname</i> will, depending on the functions used, have a value and a time component. When you use this <i>vname</i> in another <b>RPN</b> expression, you are effectively inserting its value just as if you had put a number at that place. The variable can also be used in the various graph and print elements.</p>

<p>Example: <code>VDEF:avg=mydata,AVERAGE</code></p>

<p>Note that currently only aggregation functions work in VDEF rpn expressions. Patches to change this are welcome.</p>

<h1 id="CDEF">CDEF</h1>

<p><b>CDEF</b>:<i>vname</i>=<i>RPN expression</i></p>

<p>This command creates a new set of data points (in memory only, not in the <b>RRD</b> file) out of one or more other data series. The <b>RPN</b> instructions are used to evaluate a mathematical function on each data point. The resulting <i>vname</i> can then be used further on in the script, just as if it were generated by a <b>DEF</b> instruction.</p>

<p>Example: <code>CDEF:mydatabits=mydata,8,*</code></p>

<h1 id="About-CDEF-versus-VDEF">About CDEF versus VDEF</h1>

<p>At some point in processing, <b>RRDtool</b> has gathered an array of rates ready to display.</p>

<p><b>CDEF</b> works on such an array. For example, <i>CDEF:new=ds0,8,*</i> would multiply each of the array members by eight (probably transforming bytes into bits). The result is an array containing the new values.</p>

<p><b>VDEF</b> also works on such an array but in a different way. For example, <i>VDEF:max=ds0,MAXIMUM</i> would scan each of the array members and store the maximum value.</p>

<h2 id="When-do-you-use-VDEF-versus-CDEF">When do you use <b>VDEF</b> versus <b>CDEF</b>?</h2>

<p>Use <b>CDEF</b> to transform your data prior to graphing. In the above example, we&#39;d use a <b>CDEF</b> to transform bytes to bits before graphing the bits.</p>

<p>You use a <b>VDEF</b> if you want <i>max(1,5,3,2,4)</i> to return five which would be displayed in the graph&#39;s legend (to answer, what was the maximum value during the graph period).</p>

<p>If you want to apply &#39;complex&#39; operations to the result of a VDEF you have to use a CDEF again since VDEFs only look like RPN expressions, they aren&#39;t really.</p>

<h1 id="SEE-ALSO">SEE ALSO</h1>

<p><a href="./rrdgraph.html">rrdgraph</a> gives an overview of how <b>rrdtool graph</b> works. <a href="./rrdgraph_data.html">rrdgraph_data</a> describes <b>DEF</b>,<b>CDEF</b> and <b>VDEF</b> in detail. <a href="./rrdgraph_rpn.html">rrdgraph_rpn</a> describes the <b>RPN</b> language used in the <b>?DEF</b> statements. <a href="./rrdgraph_graph.html">rrdgraph_graph</a> page describes all of the graph and print functions.</p>

<p>Make sure to read <a href="./rrdgraph_examples.html">rrdgraph_examples</a> for tips&amp;tricks.</p>

<h1 id="AUTHOR">AUTHOR</h1>

<p>Program by Tobias Oetiker &lt;tobi@oetiker.ch&gt;</p>

<p>This manual page by Alex van den Bogaerdt &lt;alex@vandenbogaerdt.nl&gt; with corrections and/or additions by several people</p>


</body>

</html>


